"Batch API"는 여러 개의 작업(요청)을 하나의 요청/응답으로 묶어 처리할 수 있게 해주는 API를 뜻합니다. 문맥에 따라 두 가지 의미로 쓰입니다. 1) 클라이언트에서 여러 API 호출을 하나의 HTTP 요청으로 묶는 배치 엔드포인트 - 예: 모바일 앱이 한 번의 네트워크 호출로 여러 자원 조회/수정(여러 REST 호출)을 수행하게 하는 /batch 또는 /bulk 엔드포인트. - 요청 본문은 보통 작업 목록(예: JSON 배열, multipart/mixed 등)을 포함하고, 서버는 각 작업의 처리 결과를 묶어서 응답합니다. 2) 서버·백엔드에서 많은 데이터를 일괄 처리하는 배치 작업용 API - 예: 대량 데이터 적재(ETL), 로그 집계, 정기 보고서 생성 등. 즉 비동기 작업(job)을 등록/조회/관리하는 API(예: /jobs, /tasks, /import). - 작업은 보통 큐에 들어가고 백그라운드에서 처리되며 상태 조회와 결과 수집 기능이 제공됩니다. 주요 장점 - 네트워크 오버헤드 감소: 여러 개별 호출 대신 하나의 요청으로 RTT 및 헤더 비용 절감. - 처리량 향상: 서버 쪽에서 배치 최적화(데이터베이스 bulk insert 등)를 통해 효율적 처리 가능. - 트랜잭션성 확보: 필요 시 여러 작업을 원자적으로 처리하도록 설계 가능(all-or-nothing). 단점·주의사항 - 응답 지연: 대량 작업은 단일 요청이 오래 걸리거나 타임아웃 발생 가능. - 복잡한 오류 처리: 일부 작업만 실패하는 경우의 규칙(부분 성공 vs 전체 롤백)을 명확히 해야 함. - 페이로드 크기 제한 및 메모리 부담: 큰 배치는 요청·응답 크기 때문에 제한 필요. - 재시도·중복 문제: 배치 요청은 idempotency(멱등성) 설계가 중요. 오류 처리 방식(일반적 패턴) - 전부 실패(atomic): 한 항목 실패 시 전체 롤백, 클라이언트는 재시도. - 항목별 결과: 응답에 각 항목별 상태(HTTP 코드, 오류 메시지)를 반환하여 부분 성공 허용. - 트랜잭션 단위 배치: 서브그룹별 원자성 보장. 설계 권장사항(베스트 프랙티스) - 배치 크기 제한을 명시(개수, 바이트). - 각 작업에 고유 ID 포함(멱등성 및 재시도용). - 부분 성공 정책을 문서화하고, 항목별 오류 포맷을 표준화. - 비동기 처리 필요 시 작업 등록 + 상태 조회(API polling or webhook) 제공. - 타임아웃·재시도·백프레셔(Throttling) 전략 마련. - 보안 고려: 인증·권한 검사·입력 검증을 배치 수준과 항목 수준에서 모두 수행. 간단한 예시(개념) - 동기형 JSON 배치 요청: [{ "method": "POST", "path": "/orders", "body": {...} }, { "method": "GET", "path": "/products/42" }] - 비동기형 작업 등록: POST /imports { "fileUrl": "...", "options": {...} } -> 응답으로 jobId 반환, 이후 GET /jobs/{jobId}로 상태 조회. 주요 사용 사례 - 모바일/웹에서 네트워크 호출 수 줄이기 - 다수의 레코드 일괄 생성/갱신(데이터 업로드, CSV 임포트) - 분석 파이프라인, 로그 집계, 정기 배치 보고서 - API 소비 비용(요청당 과금) 최적화 요약 - Batch API는 여러 작업을 묶어 효율적으로 처리하도록 하는 방식으로, 네트워크/처리 효율을 크게 높일 수 있지만 오류 처리, 페이로드 크기, 멱등성 등 설계상의 고려사항이 많습니다. 설계 시 배치 크기, 실패 정책(전부 실패 vs 항목별 결과), 비동기 처리·상태 조회, 멱등성 보장 등을 명확히 하는 것이 중요합니다.
